<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<title>GXPage</title>
		<meta http-equiv="Content-Language" content="en-US" />
		<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
		<script type="text/javascript" src="Themes/Default/Assets/jquery-1.1.2.pack.js"></script>
		<style type="text/css">
		* {
			font-family: sans-serif;
		}

		code {
			display: block;
			margin-left: 50px;
			padding-left: 20px;
			white-space: pre;
			background-color: #efefef;
		}
		</style>
	</head>
	<body>
		<div id="toc">
			toc
		</div>

		<h1>GXPage <span>PHP Website Toolbox</span></h1>

		<h2>Definition</h2>
		<p>
			GXPage is yet another PHP framework.
			It's not influenced by Ruby on Rails or by Zend's framework.
			It was built with one idea in mind: to separate data from code from presentation by ruthlessly enforcing the use of XML.
		</p>
		<p>
			There is no output buffer.
			You can't create HTML code in your PHP functions.
			Your functions <i>must</i> return XML in the form of DOMDocument, SimpleXML or GXPage's GXXML.
			It works like this:
			<ul>
				<li>You define your Website hierarchy in an XML file</li>
				<li>You store your content in XML pages</li>
				<li>You write your functionality in PHP code, which GXPage processes and embeds where you tell it</li>
				<li>GXPage then transforms the resulting XML with your XSL Style Sheets and presents the results</li>
			</ul>
			Aside from that, it makes as few assumptions as possible.
		</p>

		<h2>Conceptual Overview</h2>
		<h3>Request Handling</h3>
		<p>
			GXPage understands two types of request:
			<ul>
				<li>Page: something that will be displayed in the user's browser, e.g., a page with content</li>
				<li>Action: performs some function and then instructs GXPage to display a particular Page (Actions can display also, but we'll get into that later)</li>
			</ul>
		</p>
		<p>
			Either type can be specified as Public (available to anyone) or Protected (available to those who have logged in).
			GXPage checks authentication directives for you.
		</p>
		<h3>Page</h3>
		<p>
			Each Page stores content in an XML file on the file system.
			That XML file can contain different languages, and can have any structure you want.
		</p>
		<h3>Action</h3>
		<p>
			You specify what object/method you want to run for each Action and what you want to do with it.
			Examples of what you can do with the results from an Action:
			<ul>
				<li>Return XML and have it threaded into a specific spot in a Page</li>
				<li>Return binary data and have it download</li>
				<li>Perform some function and then call a different Action or Page without outputting anything</li>
			</ul>
		</p>
		<h3>Theme</h3>
		<p>
			Each Page can have its own graphical user interface (called a Theme).
			Themes contain images, CSS, JavaScript and XSL (which generates that Theme's HTML).
		</p>
		<h3>Transformation</h3>
		<p>
			GXPage can transform your XML with your XSL on the server, or it can set it up so that your user's browser will do it.
			Either way, the transformation results in exactly what you wrote in XSL: HTML, WAP, WML, etc.
		</p>
		<h3>Configuration</h3>
		<p>
			Your Website is configured with two files:
			<ul>
				<li>Site.xml: defines the structure of your Website</li>
				<li>System.xml: controls various options in GXPage</li>
			</ul>
		</p>
		<p>
			GXPage uses Site.xml to determine how to handle a request.
			This structure can be used to generate a site map for submission to Google or Yahoo, and GXPage uses it to generate the list of pages available to your user at the time of the request.
		</p>

		<h2>GXPage Default Configuration</h2>
		<p>
			GXPage has a preferred way of working, and ships with its own recommended directory layout and XSL files.
			This section describes GXPage's defaults.
		</p>
		<h3>Page XML</h3>
		<p>
			The top-level node <i>must</i> be &lt;Page&gt;.
			Within that are &lt;Section&gt; nodes with an xml:lang attribute.
			Each &lt;Section&gt; contains all content for its Page in all the languages its Page is translated into.
		</p>
		<p>
			You can use this default structure or you can define your own.
		</p>

		<h2>Hello World</h2>
		<p>
			Install GXPage.
			You'll end up with a directory structure like this:
			<ul>
				<li>Config</li>
				<li>GXPage</li>
				<li>Library</li>
				<li>Pages</li>
				<li>Themes</li>
				<li>index.php</li>
				<li>error.php</li>
			</ul>
		</p>
		<p>
			You can use any directory structure you want by modifying System.xml, and you can place GXPage anywhere on your server by modifying index.php.
			This example assumes the default structure.
		</p>
		<p>
			Inside Config is Site.xml and System.xml.
			For this example, we only need to modify Site.xml.
			Open it in your favorite text editor.
		</p>
		<p>
			You'll notice there is a Page node with an @ID of "_GX".
			This section contains actions that call functionality built into GXPage.
			Leave this alone for now.
		</p>
		<p>
			The first Page node has an @ID of "Home".
			It should look like this:
			<code>
&lt;Page ID="Home" Visible="1" Trust="Public"&gt;
	&lt;Title&gt;Click me&lt;/Title&gt;
	&lt;File&gt;Home.xml&lt;/File&gt;
	&lt;Action ID="hello"&gt;
		&lt;Title&gt;Hello World&lt;/Title&gt;
		&lt;Call Object="MyObject" Method="myMethod"/&gt;
	&lt;/Action&gt;
&lt;/Page&gt;
			</code>
			For now, you can ignore the &lt;Action&gt; node.
		</p>
		<p>
			The &lt;File&gt; node specifies the file name of the XML page containing the content for that Page.
			In the default configuration, GXPage looks for these files in the Pages directory.
			Open Pages/Home.xml in your favorite text editor.
			It should look like this:
			<code>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;Page&gt;
	&lt;Section xml:lang="en-US"&gt;
		Hello World
	&lt;/Section&gt;
&lt;/Page&gt;
			</code>
		</p>
		<p>
			The default XSL Style Sheets that ship with GXPage transform that Page into an HTML page with the text "Hello World" in the middle.
			Point your browser to http://your-host/
		</p>

		<h2>Page Functions</h2>
		<h3>Embedded Actions</h3>
		<p>
			When GXPage loads your page XML, it looks for elements with @_Page and @_Action (attributes).
			You can add those attributes to any element in your XML and GXPage will execute the specified action and will embed the results within the element containing @_Page and @_Action.
			For instance, if you add &lt;MemberInfo _Page="Members" _Action="MemberOverview"/&gt; to your Page XML, the code specified in that Page/Action will replace that node.
			This makes it very easy for XSL to fire &lt;xsl:apply-templates select="your-node-name"/&gt; at that exact spot in XSL processing.
		</p>
		<h3>Always-on Actions</h3>
		<p>
			In a shopping site, it's common to show the user's shopping cart on every page.
			That means the user's cart data must appear on every page, but placing it into your XML in all your functions would be painful.
			GXPage has the &lt;Include&gt; element in System.xml.
			It is a form of &lt;Action&gt;, and if you add an &lt;Include&gt;, GXPage will include the results in the final XML page.
		</p>

		<h2>Rolling Your Own</h2>
		<p>
			Since GXPage is structured into code/data/presentation, the process for handling functionality touches all 3.
			You can add behavior to a Page, as discussed above in Embedded Actions.
		</p>

		<h2>Search Engines</h2>
		<p>
			Search engines can be picky about URL's that use parameters (?param=value&amp;param2=value2).
			For this reason, GXPage supports two methods of specifying a Page and Action:
			<ul>
				<li>As parameters: http://your-host/index.php?Page=Home&amp;Action=hello</li>
				<li>Search engine friendly: http://your-host/index.php/Home/hello</li>
			</ul>
		</p>
		<p>
			There is a very good article about search engine friendly URL's <a href="http://www.websitepublisher.net/article/search_engine_friendly_urls/">here</a>.
		</p>

		<h2>GXDOM, the Central XML Library</h2>
		<p>
			It's central, has no dependencies (other than DOM and SimpleXML) and provides a simple interface for building and working with XML documents.
		</p>

		<h2>Licensing</h2>
		<p>GXPage is licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</p>

	</body>
</html>
